feat: auto-enable SLSA L3 features when `provenance.slsa` is true #250

leodido · 2025-10-07T00:18:36Z

Description

This PR implements automatic SLSA Level 3 feature activation when provenance.slsa: true is configured in WORKSPACE.yaml.

Problem

Previously, SLSA L3 features required manual configuration of multiple environment variables:

Users had to set 4 different environment variables manually
Configuration was scattered across workspace and CI/CD scripts
provenance.slsa: true only enabled metadata generation, not runtime features
Artifacts built with/without SLSA were indistinguishable in cache (hash collision risk)

Solution

When provenance.slsa: true is set, automatically enable:

✅ Cache verification (LEEWAY_SLSA_CACHE_VERIFICATION=true)
✅ In-flight checksums (LEEWAY_ENABLE_IN_FLIGHT_CHECKSUMS=true)
✅ Docker export mode (LEEWAY_DOCKER_EXPORT_TO_CACHE=true)
✅ Source URI (LEEWAY_SLSA_SOURCE_URI from Git origin)

Key Changes

1. Workspace Auto-Enablement

# WORKSPACE.yaml
provenance:
  enabled: true
  slsa: true    # ← Automatically enables all SLSA L3 features

2. Five-Layer Precedence for Docker Export

1. CLI flag (--docker-export-to-cache)           [Highest]
2. User environment variable (set before build)
3. Package config (exportToCache in BUILD.yaml)
4. Workspace default (auto-set by provenance.slsa)
5. Global default (false - legacy)               [Lowest]

3. Package-Level Override

# BUILD.yaml - opt out of workspace default
packages:
  - name: legacy-service
    type: docker
    config:
      exportToCache: false  # Explicit override

4. Artifact Distinguishability

Artifacts built with SLSA include provenance: version=3 slsa in manifest, ensuring different cache keys than legacy builds.

Technical Changes

Changed ExportToCache bool → ExportToCache *bool (distinguishes "not set" from "explicitly false")
Added ApplySLSADefaults() in workspace loading
Track user-set env vars before workspace loads (enables precedence)
Implement 5-layer precedence in buildDocker()
16 new test scenarios covering all precedence layers

Usage Examples

Enable SLSA L3 globally:

# WORKSPACE.yaml
provenance:
  enabled: true
  slsa: true    # All packages inherit SLSA features

Package opts out:

packages:
  - name: legacy
    type: docker
    config:
      exportToCache: false  # Push directly (legacy mode)

User override for testing:

export LEEWAY_DOCKER_EXPORT_TO_CACHE=false
leeway build :backend

CLI override:

leeway build --docker-export-to-cache=true :backend

Backward Compatibility

✅ 100% backward compatible:

Existing workspaces without provenance.slsa: true unchanged
Explicit environment variables take precedence over auto-set
All existing tests passing

Related Issue(s)

Fixes https://linear.app/ona-team/issue/CLC-2018/implement-slsa-l3-workspace-driven-auto-enablement-leeway

How to test

1. Verify Auto-Enablement

cat > WORKSPACE.yaml <<EOF
provenance:
  enabled: true
  slsa: true
EOF

leeway build -v :package 2>&1 | grep "SLSA provenance enabled"
# Should see: "SLSA provenance enabled - activating SLSA L3 runtime features"

env | grep LEEWAY_
# Should see all 4 env vars set to "true"

2. Test Precedence Layers

# Layer 4: Workspace default (SLSA enabled)
leeway build -v :docker-pkg 2>&1 | grep "workspace_default"

# Layer 3: Package config overrides workspace
# Add exportToCache: false to BUILD.yaml
leeway build -v :docker-pkg 2>&1 | grep "package_config"

# Layer 2: User env var overrides package
export LEEWAY_DOCKER_EXPORT_TO_CACHE=true
leeway build -v :docker-pkg 2>&1 | grep "user_env_var"

# Layer 1: CLI flag overrides everything
leeway build --docker-export-to-cache=false -v :docker-pkg 2>&1 | grep "cli_flag"

3. Test Artifact Distinguishability

# Build WITHOUT SLSA
cat > WORKSPACE.yaml <<EOF
provenance:
  enabled: false
EOF
leeway build :package
VERSION_1=$(leeway describe version :package)

# Build WITH SLSA
cat > WORKSPACE.yaml <<EOF
provenance:
  enabled: true
  slsa: true
EOF
leeway build :package
VERSION_2=$(leeway describe version :package)

# Verify different hashes
test "$VERSION_1" != "$VERSION_2" && echo "✅ Artifacts distinguishable"

# Check manifest
leeway describe manifest :package | grep "provenance: version=3 slsa"

4. Run Tests

# New tests
go test ./pkg/leeway/workspace_test.go -v -run TestWorkspace_ApplySLSADefaults
go test ./pkg/leeway/build_test.go -v -run TestDockerExport_PrecedenceHierarchy

# Full suite
go test ./pkg/leeway/... -v

Expected: 16 new test scenarios, all passing

5. Test Backward Compatibility

# Existing workspace without provenance.slsa
cat > WORKSPACE.yaml <<EOF
# No provenance config
EOF
leeway build :package
# Should work exactly as before

# User env vars preserved
export LEEWAY_DOCKER_EXPORT_TO_CACHE=false
cat > WORKSPACE.yaml <<EOF
provenance:
  enabled: true
  slsa: true
EOF
env | grep LEEWAY_DOCKER_EXPORT_TO_CACHE
# Should show: false (user value not overwritten)

Documentation

README.md updated with:
- Fixed SLSA version reference (v0.1 → v0.2)
- "Automatic SLSA L3 Feature Activation" section
- Configuration precedence documentation
- Usage examples and troubleshooting

/hold

SUMMARY When provenance.slsa: true is configured in WORKSPACE.yaml, automatically enable all SLSA L3 runtime features to ensure build integrity and supply chain security. FEATURES Automatically enables when provenance.slsa: true: - Cache verification (LEEWAY_SLSA_CACHE_VERIFICATION=true) - In-flight checksums (LEEWAY_ENABLE_IN_FLIGHT_CHECKSUMS=true) - Docker export mode (LEEWAY_DOCKER_EXPORT_TO_CACHE=true) - Source URI (LEEWAY_SLSA_SOURCE_URI from Git origin) PRECEDENCE HIERARCHY Implements 5-layer precedence for Docker export mode: 1. CLI flag (--docker-export-to-cache) - highest priority 2. User environment variable (set before workspace loading) 3. Package config (exportToCache in BUILD.yaml) 4. Workspace default (auto-set by provenance.slsa: true) 5. Global default (false - legacy behavior) BREAKING CHANGES - ExportToCache field changed from bool to *bool in DockerPkgConfig - Enables pointer-based detection: nil (not set) vs false (explicit) - Allows package-level overrides of workspace SLSA defaults ARTIFACT DISTINGUISHABILITY Artifacts built with SLSA enabled include "provenance: version=3 slsa" in their manifest, changing the version hash. This ensures SLSA L3 artifacts are automatically distinguishable from legacy artifacts in the cache, preventing collision and enabling proper verification. BACKWARD COMPATIBILITY Fully backward compatible: - Existing workspaces without provenance.slsa continue working unchanged - Explicit environment variables take precedence over auto-set values - Package-level exportToCache config still respected - All existing tests updated and passing DOCUMENTATION - Fixed SLSA version reference (v0.1 → v0.2) - Added "Automatic SLSA L3 Feature Activation" section - Added configuration precedence documentation - Added 4 usage scenarios with examples - Added troubleshooting guidance TESTING - 16 new test scenarios covering all precedence layers - TestDockerExport_PrecedenceHierarchy: 11 scenarios - TestWorkspace_ApplySLSADefaults: 5 scenarios - All existing tests updated for pointer-based config - Smoke test verified in real workspace Co-authored-by: Ona <[email protected]>

leodido self-assigned this Oct 7, 2025

leodido marked this pull request as ready for review October 7, 2025 00:23

leodido requested review from aledbf, csweichel and geropl October 7, 2025 00:23

leodido force-pushed the leo/slsa-workspace branch from 4490897 to 3facf99 Compare October 7, 2025 10:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: auto-enable SLSA L3 features when `provenance.slsa` is true #250

feat: auto-enable SLSA L3 features when `provenance.slsa` is true #250

leodido commented Oct 7, 2025 •

edited

Loading

Uh oh!

Uh oh!

feat: auto-enable SLSA L3 features when provenance.slsa is true #250

Are you sure you want to change the base?

feat: auto-enable SLSA L3 features when provenance.slsa is true #250

Conversation

leodido commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Problem

Solution

Key Changes

Technical Changes

Usage Examples

Backward Compatibility

Related Issue(s)

How to test

1. Verify Auto-Enablement

2. Test Precedence Layers

3. Test Artifact Distinguishability

4. Run Tests

5. Test Backward Compatibility

Documentation

Uh oh!

Uh oh!

feat: auto-enable SLSA L3 features when `provenance.slsa` is true #250

feat: auto-enable SLSA L3 features when `provenance.slsa` is true #250

leodido commented Oct 7, 2025 •

edited

Loading